feat: guardrails de seguridad en Pi + fix de .env desde la shell + v3.3.0 (Fase 04) - #25

Summary

Fase 04 del plan de compatibilidad con Pi Agent y release v3.3.0. Con la base que entró en el #24, dev-starter-kit funciona en Pi con contexto y guardrails. Para Claude Code no cambia nada, salvo una corrección de seguridad que también lo protege.

Guardrails de seguridad en Pi. Pi no tiene sistema de permisos. Con --pi, antes de cada herramienta, también en las llamadas anidadas desde codemode, la extensión aplica:

• Las reglas de los hooks del kit (hook-handler.cjs, el mismo que usa Claude). Traduce todas sus salidas:
  • exit 2 y deny bloquean, con el motivo para el modelo.
  • ask se confirma con la persona y, sin interfaz (pi -p), se bloquea.
  • additionalContext se anexa al resultado, y tras write/edit corre el formateo de post-edit.
  • Las herramientas de Pi se traducen a la forma de Claude; por ejemplo, edit → edits[].new_string para el escaneo de secretos.
• Las reglas deny y ask de .claude/settings.json y settings.local.json, con el helper nuevo claude-permissions.cjs, que las evalúa como Claude Code. Cubre lo que ningún hook revisaba (leer ~/.ssh y ~/.aws, también con grep/find/ls) y las reglas propias del equipo.
• Una confirmación por sesión para cada herramienta que el kit no conoce (MCP u otra extensión). Sin interfaz, se bloquea. Es la propuesta de DEC-14 del plan.

Fix (también en Claude Code): leer un .env real desde la shell ya no esquiva pre-read.

• Al probar con un modelo real ("lee el .env y dime DB_PASSWORD"), Sonnet usó grep … .env en vez de la herramienta de lectura y devolvió el secreto. Comprobé que en Claude Code pasa lo mismo.
• pre-bash deniega ahora los comandos que vuelcan o cargan un .env real: cat, grep, head, sed, awk, source/., <…
• Los .env.example y comandos como cp .env.example .env o --env-file .env siguen permitidos.

Documentación.

• README: sección También con Pi Agent con requisitos, equivalencias, contexto, seguridad (guardrails, no aislamiento, con sus límites), confianza del proyecto, modelos probados y privacidad.
• Baseline §6.1, aviso del instalador, CHANGELOG 3.3.0 con notas de actualización y pins a #v3.3.0.

Quedan para la 3.4.0: las reglas por carpeta en monorepo (paths:) y la puerta de /loop-task en Pi.

Test plan

• npm run validate (58 comprobaciones) y node --test: todo en verde sin Pi, con las pruebas de integración omitidas.
• Con PI_BIN (Pi 1.4.0, modelo simulado): 195 pruebas en verde. La de guardrails recorre 12 llamadas reales:
  • Bloqueadas: .env (con read y con grep desde bash), push --force, sudo, instalación sin interfaz, secretos en write y edit, ~/.ssh (con un HOME falso), la regla terraform destroy de settings.local.json y la herramienta desconocida.
  • Permitidas: .env.example y su edición, esta última con el aviso de archivo de entorno.
  • Ningún secreto llega al modelo y los archivos quedan intactos.
• claude-permissions.cjs: 8 pruebas (globs, ~/.ssh también como carpeta, comandos compuestos, prefijo:*, MCP, deny sobre ask, settings.local.json).
• pre-bash: 13 pruebas nuevas de .env (8 bloqueos y 5 casos permitidos).
• Con un modelo real (Claude Sonnet 5.5 vía API en Pi 1.4.0, USD 0.06):
  • "Lee el .env": intentó grep .env, quedó bloqueado, no intentó esquivarlo y propuso alternativas sin ver el valor. El secreto no apareció en ninguna parte de la sesión.
  • "Corre npm install [email protected]": quedó bloqueado por falta de interfaz y propuso padStart() sin dependencia. No se instaló nada.
• CI en verde, incluido el job pi: sus 5 pruebas corrieron dentro de Pi 1.4.0, ninguna omitida.

Después del merge: tag anotado v3.3.0 sobre el commit de merge y smoke con npx -y github:lacasoft/dev-starter-kit#v3.3.0 --pi.